Skip to main content

Accessing Customer Docs via API

alt_text

Use Case Overview​

alt_text

Client Request: Partner is seeking guidance on how to programmatically obtain the following documents for a customer:

  • Electricity Facts Label (EFL)
  • Your Rights as a Customer
  • Terms of Service (TOS)

These documents are tied to the customer's enrollment and selected plan.

Workflow Summary​

alt_text

To retrieve customer documentation, Partner must follow a multi-step API integration process using the OpsAdmin API. The process requires secure authentication and the extraction of multiple parameters that uniquely identify the customer and their selected plan.

Step-by-Step Implementation Instructions​

alt_text

1. Customer Login​

Endpoint: POST /api/v1/customers/login

  • Purpose: Authenticate the customer and retrieve the X-Customer-Hash
  • Output: X-Customer-Hash (used for secure calls)
  • Error Handling:
    • 401 Unauthorized: Invalid credentials or expired session
    • Retry login with correct credentials

More:: https://apidocs.ops-admin.com/athentication​

2. Get Customer Profile​

Endpoint: GET /api/v1/customers/{customerId}/profile

  • Purpose: Retrieve languageId for the customer
  • Output: languageId
  • **Error Handling:
    • 404 Not Found: Invalid or non-existent customerId
    • Ensure the customerId is coming from a verified login response

More: https://apidocs.ops-admin.com/customer-portal/enrollments#get-all-the-enrollments-of-a-customer​

3. Get Customer Enrollments​

Endpoint: GET /api/v1/customers/{customerId}/enrollments

  • Purpose: Retrieve latest active enrollment and extract planId
  • Note: Only the most recent enrollment is returned (excluding canceled/archived)
  • Output: planId
  • **Error Handling:
    • 404: No active enrollments found
    • Return user-friendly message or trigger manual review fallback

More: https://apidocs.ops-admin.com/customer-portal/enrollments#get-all-the-enrollments-of-a-customer​

4. Retrieve Enrollment Documents​

Endpoint: GET /api/v1/document-bundles/enrollment-documents/{planId}?languageId={languageId}

  • Headers: Include X-Customer-Hash for authorization
  • Purpose: Retrieve URLs to download the EFL, TOS, and Rights documents
  • Output:

alt_text

  • Error Handling:
    • 400 Bad Request: Missing or incorrect parameters
    • 403 Forbidden: Missing or invalid X-Customer-Hash
    • 500 Internal Server Error: Retry with backoff strategy

More: https://apidocs.ops-admin.com/customer-portal/enrollments#get-all-the-enrollments-of-a-customer​

Implementation Notes​

alt_text

  • Ensure X-Customer-Hash is refreshed upon every new login
  • Only use the most recent active enrollment
  • Documents are language-specific, and the correct languageId must be used

Security Concerns​

alt_text

  • Do not store X-Customer-Hash permanently; treat it as a session token
  • All API calls must be HTTPS with appropriate authorization headers

Summary​

alt_text

Partner can successfully access customer documentation by chaining together four OpsAdmin API calls, beginning with secure login and ending with document retrieval using the planId and languageId. The process supports personalized and compliant delivery of required energy service documents.